Repository navigation
rtsdiff circular: choose the 2π branch from the previous posterior (fixes #240) - #241
Merged
Merged
Conversation
…240) With circular=True the innovation was wrapped against the filter's prediction. After a large one-step change in angle, a high-gain prediction can overshoot the measurement by more than pi, so the wrapped innovation takes the branch 2pi away and the filter locks onto an aliased solution whose derivative is off by, or grows by, multiples of 2pi/dt. kalman_filter gains circular=True, which keeps the wrapped innovation but picks its branch relative to the previous posterior: r + wrap(y - r) - pred. rtsdiff uses it by default and keeps the old behaviour as circular_branch='prediction', which still tracks fast, steady rotation through noise better at low gain. innovation_fn is unchanged, so this is backward compatible. Tests cover the issue's step and Drosophila examples, noise robustness at the issue's gain, equivalence with differentiating unwrapped data (irregular steps, NaNs, multidim), invariance to whole turns, and argument validation. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Owner
Author
|
Verified that this fix works on a much larger dataset on a downstream repo, as well. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes #240.
Problem
With
circular=True,rtsdiffwrapped each innovation against the filter's prediction. After a large one-step change in angle (still < π), a high-gain filter's next prediction can overshoot the measurement by more than π. The wrapped innovation then takes the branch 2π away, and the filter locks onto an aliased solution whose derivative is off by, or keeps growing by, multiples of 2π/dt. Raisingorderdoesn't help: at the gainsoptimizepicks (log_qr_ratio12–14), order 2 aliases from smaller steps than order 1.Change
kalman_filter(..., circular=False): whenTrue, the innovation stays wrapped, but its branch is chosen relative to the previous posterior,r = C x̂ₙ₋₁|ₙ₋₁:r + wrap(y − r) − C x̂ₙ|ₙ₋₁. Across missing data,rfollows the model's prediction.innovation_fnkeeps its signature, so this is backward compatible; combining the two raisesValueError.rtsdiff(..., circular_branch='posterior'): the new rule is the default.'prediction'keeps the previous behaviour exactly, which is still the better choice for fast, steady rotation through noise at low gain. Both docstrings explain the trade-off.How the option was chosen
Prototyped against the current behaviour, a "fold the predicted increment into [−π, π]" variant,
np.unwrap+ plain filter, the wrapped Kalman filter of Traa & Smaragdis (2013), and an innovation gate. Branching from the previous posterior was the only option with no aliasing in the step sweep (orders 1–3,log_qr_ratio2–14) or on the Drosophila trajectory from the issue. On that trajectory with added noise atlog_qr_ratio12 it had no wrong-branch failures up to σ = 0.2 rad (out of 100 seeds), versus 70–100% for the current method. Its cost: on fast noisy rotation at low gain it lags, which is why'prediction'stays available.Tests
New tests in
test_diff_methods.py. The 11 #240 regression tests below fail with the old prediction-branch default:forwardbackward(8 cases)np.unwrapped data (2 cases)These also pass under both branches:
axis=1test_circular_rtsdiff, now run for both branchesChecks
coverage run --source=pynumdiff -m pytest -s: 234 passed;kalman_smooth.pyat 99%. The 2 missed lines are an existingconvex_smootherror branch.pylint pynumdiff: 9.39 (9.37 before).🤖 Generated with Claude Code